<!DOCTYPE html>
<html lang="en-us">
  <head>

    <meta http-equiv="content-type" content="text/html; charset=utf-8">
    
<meta charset="UTF-8">
<title>Put watch API | Elasticsearch Guide [7.7] | Elastic</title>
<link rel="home" href="index.html" title="Elasticsearch Guide [7.7]">
<link rel="up" href="watcher-api.html" title="Watcher APIs">
<link rel="prev" href="watcher-api-stats.html" title="Get Watcher stats API">
<link rel="next" href="watcher-api-start.html" title="Start watch service API">
<meta name="DC.type" content="Learn/Docs/Elasticsearch/Reference/7.7">
<meta name="DC.subject" content="Elasticsearch">
<meta name="DC.identifier" content="7.7">
<meta name="robots" content="noindex,nofollow">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="https://cdn.optimizely.com/js/18132920325.js"></script>
    <link rel="apple-touch-icon" sizes="57x57" href="/apple-icon-57x57.png">
    <link rel="apple-touch-icon" sizes="60x60" href="/apple-icon-60x60.png">
    <link rel="apple-touch-icon" sizes="72x72" href="/apple-icon-72x72.png">
    <link rel="apple-touch-icon" sizes="76x76" href="/apple-icon-76x76.png">
    <link rel="apple-touch-icon" sizes="114x114" href="/apple-icon-114x114.png">
    <link rel="apple-touch-icon" sizes="120x120" href="/apple-icon-120x120.png">
    <link rel="apple-touch-icon" sizes="144x144" href="/apple-icon-144x144.png">
    <link rel="apple-touch-icon" sizes="152x152" href="/apple-icon-152x152.png">
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-icon-180x180.png">
    <link rel="icon" type="image/png" href="/favicon-32x32.png" sizes="32x32">
    <link rel="icon" type="image/png" href="/android-chrome-192x192.png" sizes="192x192">
    <link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96">
    <link rel="icon" type="image/png" href="/favicon-16x16.png" sizes="16x16">
    <link rel="manifest" href="/manifest.json">
    <meta name="apple-mobile-web-app-title" content="Elastic">
    <meta name="application-name" content="Elastic">
    <meta name="msapplication-TileColor" content="#ffffff">
    <meta name="msapplication-TileImage" content="/mstile-144x144.png">
    <meta name="theme-color" content="#ffffff">
    <meta name="naver-site-verification" content="936882c1853b701b3cef3721758d80535413dbfd">
    <meta name="yandex-verification" content="d8a47e95d0972434">
    <meta name="localized" content="true">
    <meta name="st:robots" content="follow,index">
    <meta property="og:image" content="https://www.elastic.co/static/images/elastic-logo-200.png">
    <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
    <link rel="icon" href="/favicon.ico" type="image/x-icon">
    <link rel="apple-touch-icon-precomposed" sizes="64x64" href="/favicon_64x64_16bit.png">
    <link rel="apple-touch-icon-precomposed" sizes="32x32" href="/favicon_32x32.png">
    <link rel="apple-touch-icon-precomposed" sizes="16x16" href="/favicon_16x16.png">
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
    <link rel="stylesheet" type="text/css" href="/guide/static/styles.css">
  </head>

  <!--© 2015-2021 Elasticsearch B.V. Copying, publishing and/or distributing without written permission is strictly prohibited.-->

  <body>
    <!-- Google Tag Manager -->
    <script>dataLayer = [];</script><noscript><iframe src="//www.googletagmanager.com/ns.html?id=GTM-58RLH5" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
    <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= '//www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-58RLH5');</script>
    <!-- End Google Tag Manager -->

    <!-- Global site tag (gtag.js) - Google Analytics -->
    <script async src="https://www.googletagmanager.com/gtag/js?id=UA-12395217-16"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'UA-12395217-16');
    </script>

    <!--BEGIN QUALTRICS WEBSITE FEEDBACK SNIPPET-->
    <script type="text/javascript">
      (function(){var g=function(e,h,f,g){
      this.get=function(a){for(var a=a+"=",c=document.cookie.split(";"),b=0,e=c.length;b<e;b++){for(var d=c[b];" "==d.charAt(0);)d=d.substring(1,d.length);if(0==d.indexOf(a))return d.substring(a.length,d.length)}return null};
      this.set=function(a,c){var b="",b=new Date;b.setTime(b.getTime()+6048E5);b="; expires="+b.toGMTString();document.cookie=a+"="+c+b+"; path=/; "};
      this.check=function(){var a=this.get(f);if(a)a=a.split(":");else if(100!=e)"v"==h&&(e=Math.random()>=e/100?0:100),a=[h,e,0],this.set(f,a.join(":"));else return!0;var c=a[1];if(100==c)return!0;switch(a[0]){case "v":return!1;case "r":return c=a[2]%Math.floor(100/c),a[2]++,this.set(f,a.join(":")),!c}return!0};
      this.go=function(){if(this.check()){var a=document.createElement("script");a.type="text/javascript";a.src=g;document.body&&document.body.appendChild(a)}};
      this.start=function(){var a=this;window.addEventListener?window.addEventListener("load",function(){a.go()},!1):window.attachEvent&&window.attachEvent("onload",function(){a.go()})}};
      try{(new g(100,"r","QSI_S_ZN_emkP0oSe9Qrn7kF","https://znemkp0ose9qrn7kf-elastic.siteintercept.qualtrics.com/WRSiteInterceptEngine/?Q_ZID=ZN_emkP0oSe9Qrn7kF")).start()}catch(i){}})();
    </script><div id="ZN_emkP0oSe9Qrn7kF"><!--DO NOT REMOVE-CONTENTS PLACED HERE--></div>
    <!--END WEBSITE FEEDBACK SNIPPET-->

    <div id="elastic-nav" style="display:none;"></div>
    <script src="https://www.elastic.co/elastic-nav.js"></script>

    <!-- Subnav -->
    <div>
      <div>
        <div class="tertiary-nav d-none d-md-block">
          <div class="container">
            <div class="p-t-b-15 d-flex justify-content-between nav-container">
              <div class="breadcrum-wrapper"><span><a href="/guide/" style="font-size: 14px; font-weight: 600; color: #000;">Docs</a></span></div>
            </div>
          </div>
        </div>
      </div>
    </div>

    <div class="main-container">
      <section id="content">
        <div class="content-wrapper">

          <section id="guide" lang="en">
            <div class="container">
              <div class="row">
                <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                  <!-- start body -->
                  <div class="page_header">
<strong>IMPORTANT</strong>: No additional bug fixes or documentation updates
will be released for this version. For the latest information, see the
<a href="../current/index.html">current release documentation</a>.
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="rest-apis.html">REST APIs</a></span>
»
<span class="breadcrumb-link"><a href="watcher-api.html">Watcher APIs</a></span>
»
<span class="breadcrumb-node">Put watch API</span>
</div>
<div class="navheader">
<span class="prev">
<a href="watcher-api-stats.html">« Get Watcher stats API</a>
</span>
<span class="next">
<a href="watcher-api-start.html">Start watch service API »</a>
</span>
</div>
<div class="section xpack">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="watcher-api-put-watch"></a>Put watch API<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/rest-api/watcher/put-watch.asciidoc">edit</a><a class="xpack_tag" href="/subscriptions"></a>
</h2>
</div></div></div>

<p>Either registers a new watch in Watcher or updates an existing one.</p>
<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="watcher-api-put-watch-request"></a>Request<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/rest-api/watcher/put-watch.asciidoc">edit</a>
</h3>
</div></div></div>
<p><code class="literal">PUT _watcher/watch/&lt;watch_id&gt;</code></p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="watcher-api-put-watch-prereqs"></a>Prerequisites<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/rest-api/watcher/put-watch.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
You must have <code class="literal">manage_watcher</code> cluster privileges to use this API. For more
information, see <a class="xref" href="security-privileges.html" title="Security privileges">Security privileges</a>.
</li>
</ul>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="watcher-api-put-watch-desc"></a>Description<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/rest-api/watcher/put-watch.asciidoc">edit</a>
</h3>
</div></div></div>
<p>When a watch is registered, a new document that represents the watch is added to
the <code class="literal">.watches</code> index and its trigger is immediately registered with the relevant
trigger engine. Typically for the <code class="literal">schedule</code> trigger, the scheduler is the
trigger engine.</p>
<div class="important admon">
<div class="icon"></div>
<div class="admon_content">
<p>You must use Kibana or this API to create a watch. Do not put a watch
            directly to the <code class="literal">.watches</code> index using the Elasticsearch index API.
            If Elasticsearch security features are enabled, do not give users <code class="literal">write</code>
            privileges on the <code class="literal">.watches</code> index.</p>
</div>
</div>
<p>When adding a watch you can also define its initial
<a class="xref" href="how-watcher-works.html#watch-active-state" title="Watch active state">active state</a>. You do that by setting the <code class="literal">active</code>
parameter.</p>
<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="watcher-api-put-watch-security"></a>Security integration<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/rest-api/watcher/put-watch.asciidoc">edit</a>
</h4>
</div></div></div>
<p>When Elasticsearch security features are enabled, your watch can index or search only
on indices for which the user that stored the watch has privileges. If the user
is able to read index <code class="literal">a</code>, but not index <code class="literal">b</code>, the same will apply, when the watch
is executed.</p>
</div>

</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="watcher-api-put-watch-path-params"></a>Path parameters<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/rest-api/watcher/put-watch.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">&lt;watch_id&gt;</code>
</span>
</dt>
<dd>
(Required, string) Identifier for the watch.
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="watcher-api-put-watch-query-params"></a>Query parameters<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/rest-api/watcher/put-watch.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">active</code>
</span>
</dt>
<dd>
(Optional, boolean) Defines whether the watch is active or inactive by default.
The default value is <code class="literal">true</code>, which means the watch is active by default.
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="watcher-api-put-watch-request-body"></a>Request body<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/rest-api/watcher/put-watch.asciidoc">edit</a>
</h3>
</div></div></div>
<p>A watch has the following fields:</p>
<div class="informaltable">
<table border="1" cellpadding="4px">
<colgroup>
<col class="col_1">
<col class="col_2">
</colgroup>
<thead>
<tr>
<th align="left" valign="top">Name</th>
<th align="left" valign="top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left" valign="top"><p><code class="literal">trigger</code></p></td>
<td align="left" valign="top"><p>The <a class="xref" href="trigger.html" title="Triggers">trigger</a> that defines when
                      the watch should run.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">input</code></p></td>
<td align="left" valign="top"><p>The <a class="xref" href="input.html" title="Inputs">input</a> that defines the input
                      that loads the data for the watch.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">condition</code></p></td>
<td align="left" valign="top"><p>The <a class="xref" href="condition.html" title="Conditions">condition</a> that defines if
                      the actions should be run.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">actions</code></p></td>
<td align="left" valign="top"><p>The list of <a class="xref" href="actions.html" title="Actions">actions</a> that will be
                      run if the condition matches</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">metadata</code></p></td>
<td align="left" valign="top"><p>Metadata json that will be copied into the history entries.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">throttle_period</code></p></td>
<td align="left" valign="top"><p>The minimum time between actions being run, the default
                      for this is 5 seconds. This default can be changed in the
                      config file with the setting
                      <code class="literal">xpack.watcher.throttle.period.default_period</code>. If both
                      this value and the <code class="literal">throttle_period_in_millis</code> parameter
                      are specified, Watcher uses the last parameter
                      included in the request.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">throttle_period_in_millis</code></p></td>
<td align="left" valign="top"><p>Minimum time in milliseconds between actions
                                being run. Defaults to <code class="literal">5000</code>. If both this
                                value and the <code class="literal">throttle_period</code> parameter are
                                specified, Watcher uses the last parameter
                                included in the request.</p></td>
</tr>
</tbody>
</table>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="watcher-api-put-watch-example"></a>Examples<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/rest-api/watcher/put-watch.asciidoc">edit</a>
</h3>
</div></div></div>
<p>The following example adds a watch with the <code class="literal">my-watch</code> id that has the following
characteristics:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
The watch schedule triggers every minute.
</li>
<li class="listitem">
The watch search input looks for any 404 HTTP responses that occurred in the
last five minutes.
</li>
<li class="listitem">
The watch condition checks if any search hits where found.
</li>
<li class="listitem">
When found, the watch action sends an email to an administrator.
</li>
</ul>
</div>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT _watcher/watch/my-watch
{
  "trigger" : {
    "schedule" : { "cron" : "0 0/1 * * * ?" }
  },
  "input" : {
    "search" : {
      "request" : {
        "indices" : [
          "logstash*"
        ],
        "body" : {
          "query" : {
            "bool" : {
              "must" : {
                "match": {
                   "response": 404
                }
              },
              "filter" : {
                "range": {
                  "@timestamp": {
                    "from": "{{ctx.trigger.scheduled_time}}||-5m",
                    "to": "{{ctx.trigger.triggered_time}}"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "condition" : {
    "compare" : { "ctx.payload.hits.total" : { "gt" : 0 }}
  },
  "actions" : {
    "email_admin" : {
      "email" : {
        "to" : "admin@domain.host.com",
        "subject" : "404 recently encountered"
      }
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2185.console"></div>
<p>When you add a watch you can also define its initial
<a class="xref" href="how-watcher-works.html#watch-active-state" title="Watch active state">active state</a>. You do that
by setting the <code class="literal">active</code> parameter. The following command adds a watch and sets
it to be inactive by default:</p>
<div class="pre_wrapper lang-js">
<pre class="programlisting prettyprint lang-js">PUT _watcher/watch/my-watch?active=false</pre>
</div>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>If you omit the <code class="literal">active</code> parameter, the watch is active by default.</p>
</div>
</div>
</div>

</div>
<div class="navfooter">
<span class="prev">
<a href="watcher-api-stats.html">« Get Watcher stats API</a>
</span>
<span class="next">
<a href="watcher-api-start.html">Start watch service API »</a>
</span>
</div>
</div>

                  <!-- end body -->
                </div>
                <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                  <div id="rtpcontainer" style="display: block;">
                    <div class="mktg-promo">
                      <h3>Most Popular</h3>
                      <ul class="icons">
                        <li class="icon-elasticsearch-white"><a href="https://www.elastic.co/webinars/getting-started-elasticsearch?baymax=default&amp;elektra=docs&amp;storm=top-video">Get Started with Elasticsearch: Video</a></li>
                        <li class="icon-kibana-white"><a href="https://www.elastic.co/webinars/getting-started-kibana?baymax=default&amp;elektra=docs&amp;storm=top-video">Intro to Kibana: Video</a></li>
                        <li class="icon-logstash-white"><a href="https://www.elastic.co/webinars/introduction-elk-stack?baymax=default&amp;elektra=docs&amp;storm=top-video">ELK for Logs &amp; Metrics: Video</a></li>
                      </ul>
                    </div>
                  </div>
                </div>
              </div>
            </div>
          </section>

        </div>


<div id="elastic-footer"></div>
<script src="https://www.elastic.co/elastic-footer.js"></script>
<!-- Footer Section end-->

      </section>
    </div>

<script src="/guide/static/jquery.js"></script>
<script type="text/javascript" src="/guide/static/docs.js"></script>
<script type="text/javascript">
  window.initial_state = {}</script>
  </body>
</html>
